home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimptexttool.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  20.5 KB  |  396 lines
  1. <refentry id="libgimp-gimptexttool" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimptexttool</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimptexttool</refname><refpurpose></refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. <link linkend="gint32">gint32</link>      <link linkend="gimp-text-fontname">gimp_text_fontname</link>              (<link linkend="gint32">gint32</link> image_ID,
  18.                                              <link linkend="gint32">gint32</link> drawable_ID,
  19.                                              <link linkend="gdouble">gdouble</link> x,
  20.                                              <link linkend="gdouble">gdouble</link> y,
  21.                                              <link linkend="gchar">gchar</link> *text,
  22.                                              <link linkend="gint">gint</link> border,
  23.                                              <link linkend="gboolean">gboolean</link> antialias,
  24.                                              <link linkend="gdouble">gdouble</link> size,
  25.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  26.                                              <link linkend="gchar">gchar</link> *fontname);
  27. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-text-get-extents-fontname">gimp_text_get_extents_fontname</link>  (<link linkend="gchar">gchar</link> *text,
  28.                                              <link linkend="gdouble">gdouble</link> size,
  29.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  30.                                              <link linkend="gchar">gchar</link> *fontname,
  31.                                              <link linkend="gint">gint</link> *width,
  32.                                              <link linkend="gint">gint</link> *height,
  33.                                              <link linkend="gint">gint</link> *ascent,
  34.                                              <link linkend="gint">gint</link> *descent);
  35. <link linkend="gint32">gint32</link>      <link linkend="gimp-text">gimp_text</link>                       (<link linkend="gint32">gint32</link> image_ID,
  36.                                              <link linkend="gint32">gint32</link> drawable_ID,
  37.                                              <link linkend="gdouble">gdouble</link> x,
  38.                                              <link linkend="gdouble">gdouble</link> y,
  39.                                              <link linkend="gchar">gchar</link> *text,
  40.                                              <link linkend="gint">gint</link> border,
  41.                                              <link linkend="gboolean">gboolean</link> antialias,
  42.                                              <link linkend="gdouble">gdouble</link> size,
  43.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  44.                                              <link linkend="gchar">gchar</link> *foundry,
  45.                                              <link linkend="gchar">gchar</link> *family,
  46.                                              <link linkend="gchar">gchar</link> *weight,
  47.                                              <link linkend="gchar">gchar</link> *slant,
  48.                                              <link linkend="gchar">gchar</link> *set_width,
  49.                                              <link linkend="gchar">gchar</link> *spacing,
  50.                                              <link linkend="gchar">gchar</link> *registry,
  51.                                              <link linkend="gchar">gchar</link> *encoding);
  52. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-text-get-extents">gimp_text_get_extents</link>           (<link linkend="gchar">gchar</link> *text,
  53.                                              <link linkend="gdouble">gdouble</link> size,
  54.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  55.                                              <link linkend="gchar">gchar</link> *foundry,
  56.                                              <link linkend="gchar">gchar</link> *family,
  57.                                              <link linkend="gchar">gchar</link> *weight,
  58.                                              <link linkend="gchar">gchar</link> *slant,
  59.                                              <link linkend="gchar">gchar</link> *set_width,
  60.                                              <link linkend="gchar">gchar</link> *spacing,
  61.                                              <link linkend="gchar">gchar</link> *registry,
  62.                                              <link linkend="gchar">gchar</link> *encoding,
  63.                                              <link linkend="gint">gint</link> *width,
  64.                                              <link linkend="gint">gint</link> *height,
  65.                                              <link linkend="gint">gint</link> *ascent,
  66.                                              <link linkend="gint">gint</link> *descent);
  67. </synopsis>
  68. </refsynopsisdiv>
  69.  
  70.  
  71.  
  72.  
  73.  
  74. <refsect1>
  75. <title>Description</title>
  76. <para>
  77.  
  78. </para>
  79. </refsect1>
  80.  
  81. <refsect1>
  82. <title>Details</title>
  83. <refsect2>
  84. <title><anchor id="gimp-text-fontname">gimp_text_fontname ()</title>
  85. <programlisting><link linkend="gint32">gint32</link>      gimp_text_fontname              (<link linkend="gint32">gint32</link> image_ID,
  86.                                              <link linkend="gint32">gint32</link> drawable_ID,
  87.                                              <link linkend="gdouble">gdouble</link> x,
  88.                                              <link linkend="gdouble">gdouble</link> y,
  89.                                              <link linkend="gchar">gchar</link> *text,
  90.                                              <link linkend="gint">gint</link> border,
  91.                                              <link linkend="gboolean">gboolean</link> antialias,
  92.                                              <link linkend="gdouble">gdouble</link> size,
  93.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  94.                                              <link linkend="gchar">gchar</link> *fontname);</programlisting>
  95. <para>
  96. Add text at the specified location as a floating selection or a new
  97. layer.
  98. </para>
  99. <para>
  100. This tool requires font information as a fontname conforming to the
  101. 'X Logical Font Description Conventions'. You can specify the
  102. fontsize in units of pixels or points, and the appropriate metric is
  103. specified using the size_type argument. The x and y parameters
  104. together control the placement of the new text by specifying the
  105. upper left corner of the text bounding box. If the antialias
  106. parameter is non-zero, the generated text will blend more smoothly
  107. with underlying layers. This option requires more time and memory to
  108. compute than non-antialiased text; the resulting floating selection
  109. or layer, however, will require the same amount of memory with or
  110. without antialiasing. If the specified drawable parameter is valid,
  111. the text will be created as a floating selection attached to the
  112. drawable. If the drawable parameter is not valid (-1), the text will
  113. appear as a new layer. Finally, a border can be specified around the
  114. final rendered text. The border is measured in pixels. If the border
  115. is specified as -1, empty spaces around the text will not be
  116. cropped.</para>
  117. <para>
  118.  
  119. </para><informaltable pgwide=1 frame="none" role="params">
  120. <tgroup cols="2">
  121. <colspec colwidth="2*">
  122. <colspec colwidth="8*">
  123. <tbody>
  124. <row><entry align="right"><parameter>image_ID</parameter> :</entry>
  125. <entry> The image.
  126. </entry></row>
  127. <row><entry align="right"><parameter>drawable_ID</parameter> :</entry>
  128. <entry> The affected drawable: (-1 for a new text layer).
  129. </entry></row>
  130. <row><entry align="right"><parameter>x</parameter> :</entry>
  131. <entry> The x coordinate for the left of the text bounding box.
  132. </entry></row>
  133. <row><entry align="right"><parameter>y</parameter> :</entry>
  134. <entry> The y coordinate for the top of the text bounding box.
  135. </entry></row>
  136. <row><entry align="right"><parameter>text</parameter> :</entry>
  137. <entry> The text to generate.
  138. </entry></row>
  139. <row><entry align="right"><parameter>border</parameter> :</entry>
  140. <entry> The size of the border.
  141. </entry></row>
  142. <row><entry align="right"><parameter>antialias</parameter> :</entry>
  143. <entry> Antialiasing.
  144. </entry></row>
  145. <row><entry align="right"><parameter>size</parameter> :</entry>
  146. <entry> The size of text in either pixels or points.
  147. </entry></row>
  148. <row><entry align="right"><parameter>size_type</parameter> :</entry>
  149. <entry> The units of specified size.
  150. </entry></row>
  151. <row><entry align="right"><parameter>fontname</parameter> :</entry>
  152. <entry> The fontname (conforming to the X Logical Font Description Conventions).
  153. </entry></row>
  154. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The new text layer.
  155. </entry></row>
  156. </tbody></tgroup></informaltable></refsect2>
  157. <refsect2>
  158. <title><anchor id="gimp-text-get-extents-fontname">gimp_text_get_extents_fontname ()</title>
  159. <programlisting><link linkend="gboolean">gboolean</link>    gimp_text_get_extents_fontname  (<link linkend="gchar">gchar</link> *text,
  160.                                              <link linkend="gdouble">gdouble</link> size,
  161.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  162.                                              <link linkend="gchar">gchar</link> *fontname,
  163.                                              <link linkend="gint">gint</link> *width,
  164.                                              <link linkend="gint">gint</link> *height,
  165.                                              <link linkend="gint">gint</link> *ascent,
  166.                                              <link linkend="gint">gint</link> *descent);</programlisting>
  167. <para>
  168. Get extents of the bounding box for the specified text.
  169. </para>
  170. <para>
  171. This tool returns the width and height of a bounding box for the
  172. specified text string with the specified font information. Ascent
  173. and descent for the specified font are returned as well.</para>
  174. <para>
  175.  
  176. </para><informaltable pgwide=1 frame="none" role="params">
  177. <tgroup cols="2">
  178. <colspec colwidth="2*">
  179. <colspec colwidth="8*">
  180. <tbody>
  181. <row><entry align="right"><parameter>text</parameter> :</entry>
  182. <entry> The text to generate.
  183. </entry></row>
  184. <row><entry align="right"><parameter>size</parameter> :</entry>
  185. <entry> The size of text in either pixels or points.
  186. </entry></row>
  187. <row><entry align="right"><parameter>size_type</parameter> :</entry>
  188. <entry> The units of specified size.
  189. </entry></row>
  190. <row><entry align="right"><parameter>fontname</parameter> :</entry>
  191. <entry> The fontname (conforming to the X Logical Font Description Conventions).
  192. </entry></row>
  193. <row><entry align="right"><parameter>width</parameter> :</entry>
  194. <entry> The width of the specified font.
  195. </entry></row>
  196. <row><entry align="right"><parameter>height</parameter> :</entry>
  197. <entry> The height of the specified font.
  198. </entry></row>
  199. <row><entry align="right"><parameter>ascent</parameter> :</entry>
  200. <entry> The ascent of the specified font.
  201. </entry></row>
  202. <row><entry align="right"><parameter>descent</parameter> :</entry>
  203. <entry> The descent of the specified font.
  204. </entry></row>
  205. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  206. </entry></row>
  207. </tbody></tgroup></informaltable></refsect2>
  208. <refsect2>
  209. <title><anchor id="gimp-text">gimp_text ()</title>
  210. <programlisting><link linkend="gint32">gint32</link>      gimp_text                       (<link linkend="gint32">gint32</link> image_ID,
  211.                                              <link linkend="gint32">gint32</link> drawable_ID,
  212.                                              <link linkend="gdouble">gdouble</link> x,
  213.                                              <link linkend="gdouble">gdouble</link> y,
  214.                                              <link linkend="gchar">gchar</link> *text,
  215.                                              <link linkend="gint">gint</link> border,
  216.                                              <link linkend="gboolean">gboolean</link> antialias,
  217.                                              <link linkend="gdouble">gdouble</link> size,
  218.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  219.                                              <link linkend="gchar">gchar</link> *foundry,
  220.                                              <link linkend="gchar">gchar</link> *family,
  221.                                              <link linkend="gchar">gchar</link> *weight,
  222.                                              <link linkend="gchar">gchar</link> *slant,
  223.                                              <link linkend="gchar">gchar</link> *set_width,
  224.                                              <link linkend="gchar">gchar</link> *spacing,
  225.                                              <link linkend="gchar">gchar</link> *registry,
  226.                                              <link linkend="gchar">gchar</link> *encoding);</programlisting>
  227. <para>
  228. Add text at the specified location as a floating selection or a new
  229. layer.
  230. </para>
  231. <para>
  232. This tool requires font information in the form of nine parameters:
  233. size, foundry, family, weight, slant, set_width, spacing, registry,
  234. encoding. The font size can either be specified in units of pixels
  235. or points, and the appropriate metric is specified using the
  236. size_type argument. The x and y parameters together control the
  237. placement of the new text by specifying the upper left corner of the
  238. text bounding box. If the antialias parameter is non-zero, the
  239. generated text will blend more smoothly with underlying layers. This
  240. option requires more time and memory to compute than non-antialiased
  241. text; the resulting floating selection or layer, however, will
  242. require the same amount of memory with or without antialiasing. If
  243. the specified drawable parameter is valid, the text will be created
  244. as a floating selection attached to the drawable. If the drawable
  245. parameter is not valid (-1), the text will appear as a new layer.
  246. Finally, a border can be specified around the final rendered text.
  247. The border is measured in pixels. If the border is specified as -1,
  248. empty spaces around the text will not be cropped.</para>
  249. <para>
  250.  
  251. </para><informaltable pgwide=1 frame="none" role="params">
  252. <tgroup cols="2">
  253. <colspec colwidth="2*">
  254. <colspec colwidth="8*">
  255. <tbody>
  256. <row><entry align="right"><parameter>image_ID</parameter> :</entry>
  257. <entry> The image.
  258. </entry></row>
  259. <row><entry align="right"><parameter>drawable_ID</parameter> :</entry>
  260. <entry> The affected drawable: (-1 for a new text layer).
  261. </entry></row>
  262. <row><entry align="right"><parameter>x</parameter> :</entry>
  263. <entry> The x coordinate for the left of the text bounding box.
  264. </entry></row>
  265. <row><entry align="right"><parameter>y</parameter> :</entry>
  266. <entry> The y coordinate for the top of the text bounding box.
  267. </entry></row>
  268. <row><entry align="right"><parameter>text</parameter> :</entry>
  269. <entry> The text to generate.
  270. </entry></row>
  271. <row><entry align="right"><parameter>border</parameter> :</entry>
  272. <entry> The size of the border.
  273. </entry></row>
  274. <row><entry align="right"><parameter>antialias</parameter> :</entry>
  275. <entry> Antialiasing.
  276. </entry></row>
  277. <row><entry align="right"><parameter>size</parameter> :</entry>
  278. <entry> The size of text in either pixels or points.
  279. </entry></row>
  280. <row><entry align="right"><parameter>size_type</parameter> :</entry>
  281. <entry> The units of specified size.
  282. </entry></row>
  283. <row><entry align="right"><parameter>foundry</parameter> :</entry>
  284. <entry> The font foundry, \"*\" for any.
  285. </entry></row>
  286. <row><entry align="right"><parameter>family</parameter> :</entry>
  287. <entry> The font family, \"*\" for any.
  288. </entry></row>
  289. <row><entry align="right"><parameter>weight</parameter> :</entry>
  290. <entry> The font weight, \"*\" for any.
  291. </entry></row>
  292. <row><entry align="right"><parameter>slant</parameter> :</entry>
  293. <entry> The font slant, \"*\" for any.
  294. </entry></row>
  295. <row><entry align="right"><parameter>set_width</parameter> :</entry>
  296. <entry> The font set-width, \"*\" for any.
  297. </entry></row>
  298. <row><entry align="right"><parameter>spacing</parameter> :</entry>
  299. <entry> The font spacing, \"*\" for any.
  300. </entry></row>
  301. <row><entry align="right"><parameter>registry</parameter> :</entry>
  302. <entry> The font registry, \"*\" for any.
  303. </entry></row>
  304. <row><entry align="right"><parameter>encoding</parameter> :</entry>
  305. <entry> The font encoding, \"*\" for any.
  306. </entry></row>
  307. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The new text layer.
  308. </entry></row>
  309. </tbody></tgroup></informaltable></refsect2>
  310. <refsect2>
  311. <title><anchor id="gimp-text-get-extents">gimp_text_get_extents ()</title>
  312. <programlisting><link linkend="gboolean">gboolean</link>    gimp_text_get_extents           (<link linkend="gchar">gchar</link> *text,
  313.                                              <link linkend="gdouble">gdouble</link> size,
  314.                                              <link linkend="GimpSizeType">GimpSizeType</link> size_type,
  315.                                              <link linkend="gchar">gchar</link> *foundry,
  316.                                              <link linkend="gchar">gchar</link> *family,
  317.                                              <link linkend="gchar">gchar</link> *weight,
  318.                                              <link linkend="gchar">gchar</link> *slant,
  319.                                              <link linkend="gchar">gchar</link> *set_width,
  320.                                              <link linkend="gchar">gchar</link> *spacing,
  321.                                              <link linkend="gchar">gchar</link> *registry,
  322.                                              <link linkend="gchar">gchar</link> *encoding,
  323.                                              <link linkend="gint">gint</link> *width,
  324.                                              <link linkend="gint">gint</link> *height,
  325.                                              <link linkend="gint">gint</link> *ascent,
  326.                                              <link linkend="gint">gint</link> *descent);</programlisting>
  327. <para>
  328. Get extents of the bounding box for the specified text.
  329. </para>
  330. <para>
  331. This tool returns the width and height of a bounding box for the
  332. specified text string with the specified font information. Ascent
  333. and descent for the specified font are returned as well.</para>
  334. <para>
  335.  
  336. </para><informaltable pgwide=1 frame="none" role="params">
  337. <tgroup cols="2">
  338. <colspec colwidth="2*">
  339. <colspec colwidth="8*">
  340. <tbody>
  341. <row><entry align="right"><parameter>text</parameter> :</entry>
  342. <entry> The text to generate.
  343. </entry></row>
  344. <row><entry align="right"><parameter>size</parameter> :</entry>
  345. <entry> The size of text in either pixels or points.
  346. </entry></row>
  347. <row><entry align="right"><parameter>size_type</parameter> :</entry>
  348. <entry> The units of specified size.
  349. </entry></row>
  350. <row><entry align="right"><parameter>foundry</parameter> :</entry>
  351. <entry> The font foundry, \"*\" for any.
  352. </entry></row>
  353. <row><entry align="right"><parameter>family</parameter> :</entry>
  354. <entry> The font family, \"*\" for any.
  355. </entry></row>
  356. <row><entry align="right"><parameter>weight</parameter> :</entry>
  357. <entry> The font weight, \"*\" for any.
  358. </entry></row>
  359. <row><entry align="right"><parameter>slant</parameter> :</entry>
  360. <entry> The font slant, \"*\" for any.
  361. </entry></row>
  362. <row><entry align="right"><parameter>set_width</parameter> :</entry>
  363. <entry> The font set-width, \"*\" for any.
  364. </entry></row>
  365. <row><entry align="right"><parameter>spacing</parameter> :</entry>
  366. <entry> The font spacing, \"*\" for any.
  367. </entry></row>
  368. <row><entry align="right"><parameter>registry</parameter> :</entry>
  369. <entry> The font registry, \"*\" for any.
  370. </entry></row>
  371. <row><entry align="right"><parameter>encoding</parameter> :</entry>
  372. <entry> The font encoding, \"*\" for any.
  373. </entry></row>
  374. <row><entry align="right"><parameter>width</parameter> :</entry>
  375. <entry> The width of the specified font.
  376. </entry></row>
  377. <row><entry align="right"><parameter>height</parameter> :</entry>
  378. <entry> The height of the specified font.
  379. </entry></row>
  380. <row><entry align="right"><parameter>ascent</parameter> :</entry>
  381. <entry> The ascent of the specified font.
  382. </entry></row>
  383. <row><entry align="right"><parameter>descent</parameter> :</entry>
  384. <entry> The descent of the specified font.
  385. </entry></row>
  386. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE on success.
  387. </entry></row>
  388. </tbody></tgroup></informaltable></refsect2>
  389.  
  390. </refsect1>
  391.  
  392.  
  393.  
  394.  
  395. </refentry>
  396.